


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Remoting (Scala) &mdash; Akka Documentation</title>
    
    <link rel="stylesheet" href="../_static/style.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="../_static/prettify.css" type="text/css" />
    <link rel="stylesheet" href="../_static/base.css" type="text/css" />
    <link rel="stylesheet" href="../_static/docs.css" type="text/css" />
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Exo:300,400,600,700" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '2.0.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/toc.js"></script>
    <script type="text/javascript" src="../_static/prettify.js"></script>
    <script type="text/javascript" src="../_static/highlightCode.js"></script>
    <script type="text/javascript" src="../_static/effects.core.js"></script>
    <script type="text/javascript" src="../_static/effects.highlight.js"></script>
    <script type="text/javascript" src="../_static/scrollTo.js"></script>
    <script type="text/javascript" src="../_static/contentsFix.js"></script>
    <link rel="shortcut icon" href="../_static/favicon.ico"/>
    <link rel="top" title="Akka Documentation" href="../index.html" />
    <link rel="up" title="Scala API" href="index.html" />
    <link rel="next" title="Serialization (Scala)" href="serialization.html" />
    <link rel="prev" title="Routing (Scala)" href="routing.html" /> 
  </head>
  <body>
  <div class="navbar">
    <div class="navbar-inner">
      <div class="container">
        <div class="navbar-logo">
          <a href="http://akka.io"><img src="../_static/logo-small.png" /></a>
        </div>    
        <ul class="nav">
          <li><a href="http://akka.io/docs">Documentation</a></li>
          <li><a href="http://akka.io/downloads">Download</a></li>
          <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>
          <li><a href="http://github.com/akka/akka">Code</a></li>           
          <li><a href="http://typesafe.com/products/typesafe-subscription">Commerical Support</a></li>
        </ul>
      </div>
    </div>
  </div>
  <div class="main">
    <div class="container">
      <div class="page-title">Remoting (Scala)</div><div class="pdf-link"><a href="http://akka.io/docs/akka/2.0.1/Akka.pdf"><img src="../_static/pdf-icon.png" style="height: 40px;" /></a></div></div>
    <div class="main-container">
      <div class="container">
        <div class="row">
          <div class="span12">
            <ul class="breadcrumb">           
              <li>
                 <span class="divider">|</span> <a href="serialization.html">Serialization (Scala)</a> <span class="divider">»</span>
              </li>
              <li>
                <a href="../index.html">Contents</a>
              </li>
              <li>
                <span class="divider">«</span> <a href="routing.html">Routing (Scala)</a> <span class="divider">|</span>
              </li>
              <li>
                Version 2.0.1
              </li>
            </ul>         
          </div>
        </div>
        <div class="row">
          <div class="span9">
            
  <div class="section" id="remoting-scala">
<span id="id1"></span><h1>Remoting (Scala)</h1>
<p>For an introduction of remoting capabilities of Akka please see <a class="reference internal" href="../general/remoting.html#remoting"><em>Location Transparency</em></a>.</p>
<div class="section" id="preparing-your-actorsystem-for-remoting">
<h2>Preparing your ActorSystem for Remoting</h2>
<p>The Akka remoting is a separate jar file. Make sure that you have the following dependency in your project:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="s">&quot;com.typesafe.akka&quot;</span> <span class="o">%</span> <span class="s">&quot;akka-remote&quot;</span> <span class="o">%</span> <span class="s">&quot;2.0.1&quot;</span>
</pre></div>
</div>
<p>To enable remote capabilities in your Akka project you should, at a minimum, add the following changes
to your <tt class="docutils literal"><span class="pre">application.conf</span></tt> file:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">akka</span> <span class="o">{</span>
  <span class="n">actor</span> <span class="o">{</span>
    <span class="n">provider</span> <span class="k">=</span> <span class="s">&quot;akka.remote.RemoteActorRefProvider&quot;</span>
  <span class="o">}</span>
  <span class="n">remote</span> <span class="o">{</span>
    <span class="n">transport</span> <span class="k">=</span> <span class="s">&quot;akka.remote.netty.NettyRemoteTransport&quot;</span>
    <span class="n">netty</span> <span class="o">{</span>
      <span class="n">hostname</span> <span class="k">=</span> <span class="s">&quot;127.0.0.1&quot;</span>
      <span class="n">port</span> <span class="k">=</span> <span class="mi">2552</span>
    <span class="o">}</span>
 <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>As you can see in the example above there are four things you need to add to get started:</p>
<ul class="simple">
<li>Change provider from <tt class="docutils literal"><span class="pre">akka.actor.LocalActorRefProvider</span></tt> to <tt class="docutils literal"><span class="pre">akka.remote.RemoteActorRefProvider</span></tt></li>
<li>Add host name - the machine you want to run the actor system on; this host
name is exactly what is passed to remote systems in order to identify this
system and consequently used for connecting back to this system if need be,
hence set it to a reachable IP address or resolvable name in case you want to
communicate across the network.</li>
<li>Add port number - the port the actor system should listen on, set to 0 to have it chosen automatically</li>
</ul>
<p>The example above only illustrates the bare minimum of properties you have to add to enable remoting.
There are lots of more properties that are related to remoting in Akka. We refer to the following
reference file for more information:</p>
<div class="highlight-none"><div class="highlight"><pre>#####################################
# Akka Remote Reference Config File #
#####################################

# This is the reference config file that contains all the default settings.
# Make your edits/overrides in your application.conf.

# comments about akka.actor settings left out where they are already in akka-
# actor.jar, because otherwise they would be repeated in config rendering.

akka {

  actor {

    serializers {
      proto = &quot;akka.serialization.ProtobufSerializer&quot;
    }


    serialization-bindings {
      # Since com.google.protobuf.Message does not extend Serializable but GeneratedMessage
      # does, need to use the more specific one here in order to avoid ambiguity
      &quot;com.google.protobuf.GeneratedMessage&quot; = proto
    }

    deployment {

      default {

        # if this is set to a valid remote address, the named actor will be deployed
        # at that node e.g. &quot;akka://sys@host:port&quot;
        remote = &quot;&quot;

        target {

          # A list of hostnames and ports for instantiating the children of a
          # non-direct router
          #   The format should be on &quot;akka://sys@host:port&quot;, where:
          #    - sys is the remote actor system name
          #    - hostname can be either hostname or IP address the remote actor
          #      should connect to
          #    - port should be the port for the remote server on the other node
          # The number of actor instances to be spawned is still taken from the
          # nr-of-instances setting as for local routers; the instances will be
          # distributed round-robin among the given nodes.
          nodes = []

        }
      }
    }
  }

  remote {

    # Which implementation of akka.remote.RemoteTransport to use
    # default is a TCP-based remote transport based on Netty
    transport = &quot;akka.remote.netty.NettyRemoteTransport&quot;

    # Enable untrusted mode for full security of server managed actors, allows
    # untrusted clients to connect.
    untrusted-mode = off

    # Timeout for ACK of cluster operations, like checking actor out etc.
    remote-daemon-ack-timeout = 30s

    # If this is &quot;on&quot;, Akka will log all inbound messages at DEBUG level, if off then they are not logged
    log-received-messages = off

    # If this is &quot;on&quot;, Akka will log all outbound messages at DEBUG level, if off then they are not logged
    log-sent-messages = off

    # Each property is annotated with (I) or (O) or (I&amp;O), where I stands for “inbound” and O for “outbound” connections.
    # The NettyRemoteTransport always starts the server role to allow inbound connections, and it starts
    # active client connections whenever sending to a destination which is not yet connected; if configured
    # it reuses inbound connections for replies, which is called a passive client connection (i.e. from server
    # to client).
    netty {

      # (O) In case of increased latency / overflow how long should we wait (blocking the sender)
      # until we deem the send to be cancelled?
      # 0 means &quot;never backoff&quot;, any positive number will indicate time to block at most.
      backoff-timeout = 0ms

      # (I&amp;O) Generate your own with &#39;$AKKA_HOME/scripts/generate_config_with_secure_cookie.sh&#39;
      # or using &#39;akka.util.Crypt.generateSecureCookie&#39;
      secure-cookie = &quot;&quot;

      # (I) Should the remote server require that its peers share the same secure-cookie
      # (defined in the &#39;remote&#39; section)?
      require-cookie = off

      # (I) Reuse inbound connections for outbound messages
      use-passive-connections = on

      # (I) The hostname or ip to bind the remoting to,
      # InetAddress.getLocalHost.getHostAddress is used if empty
      hostname = &quot;&quot;

      # (I) The default remote server port clients should connect to.
      # Default is 2552 (AKKA), use 0 if you want a random available port
      port = 2552

      # (O) The address of a local network interface (IP Address) to bind to when creating
      # outbound connections. Set to &quot;&quot; or &quot;auto&quot; for automatic selection of local address.
      outbound-local-address = &quot;auto&quot;

      # (I&amp;O) Increase this if you want to be able to send messages with large payloads
      message-frame-size = 1 MiB

      # (O) Timeout duration
      connection-timeout = 120s

      # (I) Sets the size of the connection backlog
      backlog = 4096

      # (I) Length in akka.time-unit how long core threads will be kept alive if idling
      execution-pool-keepalive = 60s

      # (I) Size of the core pool of the remote execution unit
      execution-pool-size = 4

      # (I) Maximum channel size, 0 for off
      max-channel-memory-size = 0b

      # (I) Maximum total size of all channels, 0 for off
      max-total-memory-size = 0b

      # (O) Time between reconnect attempts for active clients
      reconnect-delay = 5s

      # (O) Read inactivity period (lowest resolution is seconds)
      # after which active client connection is shutdown;
      # will be re-established in case of new communication requests.
      # A value of 0 will turn this feature off
      read-timeout = 0s

      # (O) Write inactivity period (lowest resolution is seconds)
      # after which a heartbeat is sent across the wire.
      # A value of 0 will turn this feature off
      write-timeout = 10s

      # (O) Inactivity period of both reads and writes (lowest resolution is seconds)
      # after which active client connection is shutdown;
      # will be re-established in case of new communication requests
      # A value of 0 will turn this feature off
      all-timeout = 0s

      # (O) Maximum time window that a client should try to reconnect for
      reconnection-time-window = 600s
    }

    # The dispatcher used for the system actor &quot;network-event-sender&quot;
    network-event-sender-dispatcher {
      executor = thread-pool-executor
      type = PinnedDispatcher
    }
  }
}
</pre></div>
</div>
</div>
<div class="section" id="types-of-remote-interaction">
<h2>Types of Remote Interaction</h2>
<p>Akka has two ways of using remoting:</p>
<ul class="simple">
<li>Lookup    : used to look up an actor on a remote node with <tt class="docutils literal"><span class="pre">actorFor(path)</span></tt></li>
<li>Creation  : used to create an actor on a remote node with <tt class="docutils literal"><span class="pre">actorOf(Props(...),</span> <span class="pre">actorName)</span></tt></li>
</ul>
<p>In the next sections the two alternatives are described in detail.</p>
</div>
<div class="section" id="looking-up-remote-actors">
<h2>Looking up Remote Actors</h2>
<p><tt class="docutils literal"><span class="pre">actorFor(path)</span></tt> will obtain an <tt class="docutils literal"><span class="pre">ActorRef</span></tt> to an Actor on a remote node, e.g.:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">actor</span> <span class="k">=</span> <span class="n">context</span><span class="o">.</span><span class="n">actorFor</span><span class="o">(</span><span class="s">&quot;akka://actorSystemName@10.0.0.1:2552/user/actorName&quot;</span><span class="o">)</span>
</pre></div>
</div>
<p>As you can see from the example above the following pattern is used to find an <tt class="docutils literal"><span class="pre">ActorRef</span></tt> on a remote node:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">akka</span><span class="o">://&lt;</span><span class="n">actor</span> <span class="n">system</span><span class="o">&gt;@&lt;</span><span class="n">hostname</span><span class="o">&gt;:&lt;</span><span class="n">port</span><span class="o">&gt;/&lt;</span><span class="n">actor</span> <span class="n">path</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Once you obtained a reference to the actor you can interact with it they same way you would with a local actor, e.g.:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">actor</span> <span class="o">!</span> <span class="s">&quot;Pretty awesome feature&quot;</span>
</pre></div>
</div>
<p>For more details on how actor addresses and paths are formed and used, please refer to <a class="reference internal" href="../general/addressing.html#addressing"><em>Actor References, Paths and Addresses</em></a>.</p>
</div>
<div class="section" id="creating-actors-remotely">
<h2>Creating Actors Remotely</h2>
<p>If you want to use the creation functionality in Akka remoting you have to further amend the
<tt class="docutils literal"><span class="pre">application.conf</span></tt> file in the following way (only showing deployment section):</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">akka</span> <span class="o">{</span>
  <span class="n">actor</span> <span class="o">{</span>
    <span class="n">deployment</span> <span class="o">{</span>
      <span class="o">/</span><span class="n">sampleActor</span> <span class="o">{</span>
        <span class="n">remote</span> <span class="k">=</span> <span class="s">&quot;akka://sampleActorSystem@127.0.0.1:2553&quot;</span>
      <span class="o">}</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The configuration above instructs Akka to react when an actor with path <tt class="docutils literal"><span class="pre">/sampleActor</span></tt> is created, i.e.
using <tt class="docutils literal"><span class="pre">system.actorOf(Props(...)`,</span> <span class="pre">sampleActor)</span></tt>. This specific actor will not be directly instantiated,
but instead the remote daemon of the remote system will be asked to create the actor,
which in this sample corresponds to <tt class="docutils literal"><span class="pre">sampleActorSystem&#64;127.0.0.1:2553</span></tt>.</p>
<p>Once you have configured the properties above you would do the following in code:</p>
<div class="highlight-scala"><pre>class SampleActor extends Actor { def receive = { case _ =&gt; println("Got something") } }

val actor = context.actorOf(Props[SampleActor], "sampleActor")
actor ! "Pretty slick"</pre>
</div>
<p><tt class="docutils literal"><span class="pre">SampleActor</span></tt> has to be available to the runtimes using it, i.e. the classloader of the
actor systems has to have a JAR containing the class.</p>
<div class="section" id="programmatic-remote-deployment">
<h3>Programmatic Remote Deployment</h3>
<p>To allow dynamically deployed systems, it is also possible to include
deployment configuration in the <tt class="xref py py-class docutils literal"><span class="pre">Props</span></tt> which are used to create an
actor: this information is the equivalent of a deployment section from the
configuration file, and if both are given, the external configuration takes
precedence.</p>
<p>With these imports:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">akka.actor.</span><span class="o">{</span> <span class="nc">Props</span><span class="o">,</span> <span class="nc">Deploy</span><span class="o">,</span> <span class="nc">Address</span><span class="o">,</span> <span class="nc">AddressFromURIString</span> <span class="o">}</span>
<span class="k">import</span> <span class="nn">akka.remote.RemoteScope</span>
</pre></div>
</div>
<p>and a remote address like this:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">one</span> <span class="k">=</span> <span class="nc">AddressFromURIString</span><span class="o">(</span><span class="s">&quot;akka://sys@host:1234&quot;</span><span class="o">)</span>
<span class="k">val</span> <span class="n">two</span> <span class="k">=</span> <span class="nc">Address</span><span class="o">(</span><span class="s">&quot;akka&quot;</span><span class="o">,</span> <span class="s">&quot;sys&quot;</span><span class="o">,</span> <span class="s">&quot;host&quot;</span><span class="o">,</span> <span class="mi">1234</span><span class="o">)</span> <span class="c1">// this gives the same</span>
</pre></div>
</div>
<p>you can advise the system to create a child on that remote node like so:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">ref</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">[</span><span class="kt">Echo</span><span class="o">].</span><span class="n">withDeploy</span><span class="o">(</span><span class="nc">Deploy</span><span class="o">(</span><span class="n">scope</span> <span class="k">=</span> <span class="nc">RemoteScope</span><span class="o">(</span><span class="n">address</span><span class="o">))))</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="serialization">
<h2>Serialization</h2>
<p>When using remoting for actors you must ensure that the <tt class="docutils literal"><span class="pre">props</span></tt> and <tt class="docutils literal"><span class="pre">messages</span></tt> used for
those actors are serializable. Failing to do so will cause the system to behave in an unintended way.</p>
<p>For more information please see <a class="reference internal" href="serialization.html#serialization-scala"><em>Serialization (Scala)</em></a></p>
</div>
<div class="section" id="routers-with-remote-destinations">
<h2>Routers with Remote Destinations</h2>
<p>It is absolutely feasible to combine remoting with <a class="reference internal" href="routing.html#routing-scala"><em>Routing (Scala)</em></a>.
This is also done via configuration:</p>
<div class="highlight-scala"><pre>akka {
  actor {
    deployment {
      /serviceA/aggregation {
        router = "round-robin"
        nr-of-instances = 10
        target {
          nodes = ["akka://app@10.0.0.2:2552", "akka://app@10.0.0.3:2552"]
        }
      }
    }
  }
}</pre>
</div>
<p>This configuration setting will clone the actor “aggregation” 10 times and deploy it evenly distributed across
the two given target nodes.</p>
</div>
<div class="section" id="description-of-the-remoting-sample">
<h2>Description of the Remoting Sample</h2>
<p>There is a more extensive remote example that comes with the Akka distribution.
Please have a look here for more information: <a class="reference external" href="https://github.com/akka/akka/tree/master/akka-samples/akka-sample-remote">Remote Sample</a>
This sample demonstrates both, remote deployment and look-up of remote actors.
First, let us have a look at the common setup for both scenarios (this is
<tt class="docutils literal"><span class="pre">common.conf</span></tt>):</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">akka</span> <span class="o">{</span>

  <span class="n">actor</span> <span class="o">{</span>
    <span class="n">provider</span> <span class="k">=</span> <span class="s">&quot;akka.remote.RemoteActorRefProvider&quot;</span>
  <span class="o">}</span>

  <span class="n">remote</span> <span class="o">{</span>
    <span class="n">netty</span> <span class="o">{</span>
      <span class="n">hostname</span> <span class="k">=</span> <span class="s">&quot;127.0.0.1&quot;</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>This enables the remoting by installing the <tt class="xref py py-class docutils literal"><span class="pre">RemoteActorRefProvider</span></tt> and
chooses the default remote transport. All other options will be set
specifically for each show case.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Be sure to replace the default IP 127.0.0.1 with the real address the system
is reachable by if you deploy onto multiple machines!</p>
</div>
<div class="section" id="remote-lookup">
<span id="remote-lookup-sample-scala"></span><h3>Remote Lookup</h3>
<p>In order to look up a remote actor, that one must be created first. For this
purpose, we configure an actor system to listen on port 2552 (this is a snippet
from <tt class="docutils literal"><span class="pre">application.conf</span></tt>):</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">calculator</span> <span class="o">{</span>
  <span class="n">include</span> <span class="s">&quot;common&quot;</span>

  <span class="n">akka</span> <span class="o">{</span>
    <span class="n">remote</span><span class="o">.</span><span class="n">netty</span><span class="o">.</span><span class="n">port</span> <span class="k">=</span> <span class="mi">2552</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Then the actor must be created. For all code which follows, assume these imports:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">com.typesafe.config.ConfigFactory</span>
<span class="k">import</span> <span class="nn">akka.actor.</span><span class="o">{</span> <span class="nc">ActorRef</span><span class="o">,</span> <span class="nc">Props</span><span class="o">,</span> <span class="nc">Actor</span><span class="o">,</span> <span class="nc">ActorSystem</span> <span class="o">}</span>
</pre></div>
</div>
<p>The actor doing the work will be this one:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">class</span> <span class="nc">SimpleCalculatorActor</span> <span class="k">extends</span> <span class="nc">Actor</span> <span class="o">{</span>
  <span class="k">def</span> <span class="n">receive</span> <span class="k">=</span> <span class="o">{</span>
    <span class="k">case</span> <span class="nc">Add</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">)</span> <span class="k">⇒</span>
      <span class="n">println</span><span class="o">(</span><span class="s">&quot;Calculating %d + %d&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">))</span>
      <span class="n">sender</span> <span class="o">!</span> <span class="nc">AddResult</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">n1</span> <span class="o">+</span> <span class="n">n2</span><span class="o">)</span>
    <span class="k">case</span> <span class="nc">Subtract</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">)</span> <span class="k">⇒</span>
      <span class="n">println</span><span class="o">(</span><span class="s">&quot;Calculating %d - %d&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">))</span>
      <span class="n">sender</span> <span class="o">!</span> <span class="nc">SubtractResult</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">n1</span> <span class="o">-</span> <span class="n">n2</span><span class="o">)</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>and we start it within an actor system using the above configuration</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">system</span> <span class="k">=</span> <span class="nc">ActorSystem</span><span class="o">(</span><span class="s">&quot;CalculatorApplication&quot;</span><span class="o">,</span> <span class="nc">ConfigFactory</span><span class="o">.</span><span class="n">load</span><span class="o">.</span><span class="n">getConfig</span><span class="o">(</span><span class="s">&quot;calculator&quot;</span><span class="o">))</span>
<span class="k">val</span> <span class="n">actor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">[</span><span class="kt">SimpleCalculatorActor</span><span class="o">],</span> <span class="s">&quot;simpleCalculator&quot;</span><span class="o">)</span>
</pre></div>
</div>
<p>With the service actor up and running, we may look it up from another actor
system, which will be configured to use port 2553 (this is a snippet from
<tt class="docutils literal"><span class="pre">application.conf</span></tt>).</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">remotelookup</span> <span class="o">{</span>
  <span class="n">include</span> <span class="s">&quot;common&quot;</span>

  <span class="n">akka</span> <span class="o">{</span>
    <span class="n">remote</span><span class="o">.</span><span class="n">netty</span><span class="o">.</span><span class="n">port</span> <span class="k">=</span> <span class="mi">2553</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>The actor which will query the calculator is a quite simple one for demonstration purposes</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">class</span> <span class="nc">LookupActor</span> <span class="k">extends</span> <span class="nc">Actor</span> <span class="o">{</span>
  <span class="k">def</span> <span class="n">receive</span> <span class="k">=</span> <span class="o">{</span>
    <span class="k">case</span> <span class="o">(</span><span class="n">actor</span><span class="k">:</span> <span class="kt">ActorRef</span><span class="o">,</span> <span class="n">op</span><span class="k">:</span> <span class="kt">MathOp</span><span class="o">)</span> <span class="k">⇒</span> <span class="n">actor</span> <span class="o">!</span> <span class="n">op</span>
    <span class="k">case</span> <span class="n">result</span><span class="k">:</span> <span class="kt">MathResult</span> <span class="k">⇒</span> <span class="kt">result</span> <span class="kt">match</span> <span class="o">{</span>
      <span class="kt">case</span> <span class="kt">AddResult</span><span class="o">(</span><span class="kt">n1</span><span class="o">,</span> <span class="kt">n2</span><span class="o">,</span> <span class="kt">r</span><span class="o">)</span>      <span class="k">⇒</span> <span class="n">println</span><span class="o">(</span><span class="s">&quot;Add result: %d + %d = %d&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">))</span>
      <span class="k">case</span> <span class="nc">SubtractResult</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">)</span> <span class="k">⇒</span> <span class="n">println</span><span class="o">(</span><span class="s">&quot;Sub result: %d - %d = %d&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">))</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>and it is created from an actor system using the aforementioned client’s config.</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">system</span> <span class="k">=</span> <span class="nc">ActorSystem</span><span class="o">(</span><span class="s">&quot;LookupApplication&quot;</span><span class="o">,</span> <span class="nc">ConfigFactory</span><span class="o">.</span><span class="n">load</span><span class="o">.</span><span class="n">getConfig</span><span class="o">(</span><span class="s">&quot;remotelookup&quot;</span><span class="o">))</span>
<span class="k">val</span> <span class="n">actor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">[</span><span class="kt">LookupActor</span><span class="o">],</span> <span class="s">&quot;lookupActor&quot;</span><span class="o">)</span>
<span class="k">val</span> <span class="n">remoteActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorFor</span><span class="o">(</span><span class="s">&quot;akka://CalculatorApplication@127.0.0.1:2552/user/simpleCalculator&quot;</span><span class="o">)</span>

<span class="k">def</span> <span class="n">doSomething</span><span class="o">(</span><span class="n">op</span><span class="k">:</span> <span class="kt">MathOp</span><span class="o">)</span> <span class="k">=</span> <span class="o">{</span>
  <span class="n">actor</span> <span class="o">!</span> <span class="o">(</span><span class="n">remoteActor</span><span class="o">,</span> <span class="n">op</span><span class="o">)</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Requests which come in via <tt class="docutils literal"><span class="pre">doSomething</span></tt> will be sent to the client actor
along with the reference which was looked up earlier. Observe how the actor
system name using in <tt class="docutils literal"><span class="pre">actorFor</span></tt> matches the remote system’s name, as do IP
and port number. Top-level actors are always created below the <tt class="docutils literal"><span class="pre">&quot;/user&quot;</span></tt>
guardian, which supervises them.</p>
</div>
<div class="section" id="remote-deployment">
<h3>Remote Deployment</h3>
<p>Creating remote actors instead of looking them up is not visible in the source
code, only in the configuration file. This section is used in this scenario
(this is a snippet from <tt class="docutils literal"><span class="pre">application.conf</span></tt>):</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="n">remotecreation</span> <span class="o">{</span>
  <span class="n">include</span> <span class="s">&quot;common&quot;</span>

  <span class="n">akka</span> <span class="o">{</span>
    <span class="n">actor</span> <span class="o">{</span>
      <span class="n">deployment</span> <span class="o">{</span>
        <span class="o">/</span><span class="n">advancedCalculator</span> <span class="o">{</span>
          <span class="n">remote</span> <span class="k">=</span> <span class="s">&quot;akka://CalculatorApplication@127.0.0.1:2552&quot;</span>
        <span class="o">}</span>
      <span class="o">}</span>
    <span class="o">}</span>

    <span class="n">remote</span><span class="o">.</span><span class="n">netty</span><span class="o">.</span><span class="n">port</span> <span class="k">=</span> <span class="mi">2554</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>For all code which follows, assume these imports:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">import</span> <span class="nn">com.typesafe.config.ConfigFactory</span>
<span class="k">import</span> <span class="nn">akka.actor.</span><span class="o">{</span> <span class="nc">ActorRef</span><span class="o">,</span> <span class="nc">Props</span><span class="o">,</span> <span class="nc">Actor</span><span class="o">,</span> <span class="nc">ActorSystem</span> <span class="o">}</span>
</pre></div>
</div>
<p>The client actor looks like in the previous example</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CreationActor</span> <span class="k">extends</span> <span class="nc">Actor</span> <span class="o">{</span>
  <span class="k">def</span> <span class="n">receive</span> <span class="k">=</span> <span class="o">{</span>
    <span class="k">case</span> <span class="o">(</span><span class="n">actor</span><span class="k">:</span> <span class="kt">ActorRef</span><span class="o">,</span> <span class="n">op</span><span class="k">:</span> <span class="kt">MathOp</span><span class="o">)</span> <span class="k">⇒</span> <span class="n">actor</span> <span class="o">!</span> <span class="n">op</span>
    <span class="k">case</span> <span class="n">result</span><span class="k">:</span> <span class="kt">MathResult</span> <span class="k">⇒</span> <span class="kt">result</span> <span class="kt">match</span> <span class="o">{</span>
      <span class="kt">case</span> <span class="kt">MultiplicationResult</span><span class="o">(</span><span class="kt">n1</span><span class="o">,</span> <span class="kt">n2</span><span class="o">,</span> <span class="kt">r</span><span class="o">)</span> <span class="k">⇒</span> <span class="n">println</span><span class="o">(</span><span class="s">&quot;Mul result: %d * %d = %d&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">))</span>
      <span class="k">case</span> <span class="nc">DivisionResult</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">)</span>       <span class="k">⇒</span> <span class="n">println</span><span class="o">(</span><span class="s">&quot;Div result: %.0f / %d = %.2f&quot;</span><span class="o">.</span><span class="n">format</span><span class="o">(</span><span class="n">n1</span><span class="o">,</span> <span class="n">n2</span><span class="o">,</span> <span class="n">r</span><span class="o">))</span>
    <span class="o">}</span>
  <span class="o">}</span>
<span class="o">}</span>
</pre></div>
</div>
<p>but the setup uses only <tt class="docutils literal"><span class="pre">actorOf</span></tt>:</p>
<div class="highlight-scala"><div class="highlight"><pre><span class="k">val</span> <span class="n">system</span> <span class="k">=</span> <span class="nc">ActorSystem</span><span class="o">(</span><span class="s">&quot;RemoteCreation&quot;</span><span class="o">,</span> <span class="nc">ConfigFactory</span><span class="o">.</span><span class="n">load</span><span class="o">.</span><span class="n">getConfig</span><span class="o">(</span><span class="s">&quot;remotecreation&quot;</span><span class="o">))</span>
<span class="k">val</span> <span class="n">localActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">[</span><span class="kt">CreationActor</span><span class="o">],</span> <span class="s">&quot;creationActor&quot;</span><span class="o">)</span>
<span class="k">val</span> <span class="n">remoteActor</span> <span class="k">=</span> <span class="n">system</span><span class="o">.</span><span class="n">actorOf</span><span class="o">(</span><span class="nc">Props</span><span class="o">[</span><span class="kt">AdvancedCalculatorActor</span><span class="o">],</span> <span class="s">&quot;advancedCalculator&quot;</span><span class="o">)</span>

<span class="k">def</span> <span class="n">doSomething</span><span class="o">(</span><span class="n">op</span><span class="k">:</span> <span class="kt">MathOp</span><span class="o">)</span> <span class="k">=</span> <span class="o">{</span>
  <span class="n">localActor</span> <span class="o">!</span> <span class="o">(</span><span class="n">remoteActor</span><span class="o">,</span> <span class="n">op</span><span class="o">)</span>
<span class="o">}</span>
</pre></div>
</div>
<p>Observe how the name of the server actor matches the deployment given in the
configuration file, which will transparently delegate the actor creation to the
remote node.</p>
</div>
<div class="section" id="remote-events">
<h3>Remote Events</h3>
<p>It is possible to listen to events that occur in Akka Remote, and to subscribe/unsubscribe to there events,
you simply register as listener to the below described types in on the <tt class="docutils literal"><span class="pre">ActorSystem.eventStream</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">To subscribe to any outbound-related events, subscribe to <tt class="docutils literal"><span class="pre">RemoteClientLifeCycleEvent</span></tt>
To subscribe to any inbound-related events, subscribe to <tt class="docutils literal"><span class="pre">RemoteServerLifeCycleEvent</span></tt>
To subscribe to any remote events, subscribe to <tt class="docutils literal"><span class="pre">RemoteLifeCycleEvent</span></tt></p>
</div>
<p>To intercept when an outbound connection is disconnected, you listen to <tt class="docutils literal"><span class="pre">RemoteClientDisconnected</span></tt> which
holds the transport used (RemoteTransport) and the outbound address that was disconnected (Address).</p>
<p>To intercept when an outbound connection is connected, you listen to <tt class="docutils literal"><span class="pre">RemoteClientConnected</span></tt> which
holds the transport used (RemoteTransport) and the outbound address that was connected to (Address).</p>
<p>To intercept when an outbound client is started you listen to <tt class="docutils literal"><span class="pre">RemoteClientStarted</span></tt>
which holds the transport used (RemoteTransport) and the outbound address that it is connected to (Address).</p>
<p>To intercept when an outbound client is shut down you listen to <tt class="docutils literal"><span class="pre">RemoteClientShutdown</span></tt>
which holds the transport used (RemoteTransport) and the outbound address that it was connected to (Address).</p>
<p>To intercept when an outbound message cannot be sent, you listen to <tt class="docutils literal"><span class="pre">RemoteClientWriteFailed</span></tt> which holds
the payload that was not written (AnyRef), the cause of the failed send (Throwable),
the transport used (RemoteTransport) and the outbound address that was the destination (Address).</p>
<p>For general outbound-related errors, that do not classify as any of the others, you can listen to <tt class="docutils literal"><span class="pre">RemoteClientError</span></tt>,
which holds the cause (Throwable), the transport used (RemoteTransport) and the outbound address (Address).</p>
<p>To intercept when an inbound server is started (typically only once) you listen to <tt class="docutils literal"><span class="pre">RemoteServerStarted</span></tt>
which holds the transport that it will use (RemoteTransport).</p>
<p>To intercept when an inbound server is shut down (typically only once) you listen to <tt class="docutils literal"><span class="pre">RemoteServerShutdown</span></tt>
which holds the transport that it used (RemoteTransport).</p>
<p>To intercept when an inbound connection has been established you listen to <tt class="docutils literal"><span class="pre">RemoteServerClientConnected</span></tt>
which holds the transport used (RemoteTransport) and optionally the address that connected (Option[Address]).</p>
<p>To intercept when an inbound connection has been disconnected you listen to <tt class="docutils literal"><span class="pre">RemoteServerClientDisconnected</span></tt>
which holds the transport used (RemoteTransport) and optionally the address that disconnected (Option[Address]).</p>
<p>To intercept when an inbound remote client has been closed you listen to <tt class="docutils literal"><span class="pre">RemoteServerClientClosed</span></tt>
which holds the transport used (RemoteTransport) and optionally the address of the remote client that was closed (Option[Address]).</p>
</div>
</div>
</div>


          </div>
          <div class="span3"><p class="contents-title">Contents</p>
              <div id="scroller-anchor">
                <div id="scroller">
                  <div id="toc"></div>
                </div>
              </div></div>
        </div>
      </div>
    </div>
  </div>
  <div class="footer">
  <div class="container">
    <ul>
      <li><h5>Akka</h5></li>
      <li><a href="http://akka.io/docs">Documentation</a></li>
      <li><a href="http://akka.io/downloads">Downloads</a></li>
    </ul>
    <ul>
      <li><h5>Contribute</h5></li>
      <li><a href="http://github.com/akka/akka">Source Code</a></li>
      <li><a href="http://groups.google.com/group/akka-user">Mailing List</a></li>      
      <li><a href="http://www.assembla.com/spaces/akka/tickets">Report a Bug</a></li>      
    </ul>
    <ul>
      <li><h5>Company</h5></li>
      <li><a href="http://typesafe.com/products/typesafe-subscription">Commercial Support</a></li>
      <li><a href="http://akka.io/team">Team</a></li>
      <li><a href="mailto:info@typesafe.com">Contact</a></li>
    </ul>
    <ul>
      <li><img src="../_static/watermark.png" align="center"/></li>
    </ul>
  </div>
  <div class="container copyright">
    <p style="float: left;">
      © 2012 <a href="http://typesafe.com/">Typesafe Inc.</a> <span class="license">Akka is Open Source and available under the Apache 2 License.</span>
    </p>
    <p style="float: right; font-size: 12px;">
      Last updated: Apr 13, 2012
    </p>          
  </div>
</div>
<script type="text/javascript">
  $('#toc').toc();
</script>
  

  </body>
</html>